Survey planning

Suggested workflows for the survey planning tools

This page is meant to provide some examples of how the survey planning piloting functions maybe be used ahead of a planned mission. The below sections include examples for creating a targets file, creating a planned survey map, plotting a bathymetry profile for the planned track, and summarizing total mission distance and duration.

All code on this page combined in the workflow_surveyTrackPlanning.m in the ‘example_workflows’ folder within the ‘agate-public/agate’ folder.

Details for each function used below (inputs, outputs, etc) are available within the standard MATLAB-type documentation in the header of each function and include a detailed description, info on input and output arguments, and examples. These details can be pulled up by typing doc function or help function within the MATLAB Command Window.

Initialization

To run any of the agate functions, the toolbox must be initialized with a configuration file.

No configuration file yet? Go back to Get started - Create configuration files. At a minimum, for agate to initialize, the configuration file must include the top required portion.

The examples on this page include some plotting, so the OPTIONAL - plotting section should be complete.

% !ensure agate is on the path!

% initialize with specified configuration file, 'agate_config.cnf'
agate agate_config.cnf

% OR

% initialize with prompt to select configuration file
agate

% call CONFIG so it can be used later
global CONFIG

_{Back to top}

Create targets file from .kml

The makeTargetsFile function will read in an existing .kml (that contains a single path) and use it to create a properly formatted Seaglider ‘targets’ file. The generated targets file will be named ‘targets_’ plus the name of the .kml file (e.g., ‘targets_exampleTrack’). It will contain header information with the glider and mission information defined in CONFIG, the date it was created, and the specified radius.

/ Targets file for mission sgXXX_Location_Mon20XX
/ Created on YYYY-mm-dd HH:MM UTC
/ Deployment will take place at WP01, recovery at RECV
/ template WPxx lat=DDMM.MMMM lon=DDDMM.MMMM radius=XXXX goto=WPzz

The .kml can be made in Google Earth [MORE INFO ON THAT TO COME LATER!] Track must be saved as a kml containing just a single track/path. To properly save: within Google Earth, right click on track name in left panel, select save place as, change file type from .kmz to .kml, save. An example is located in ‘agate/example_workflows/exampleTrack.kml’

Waypoint names can be generated one of three ways: (1) prefix: specify a character string prefix in the function call and alphanumeric names will be created automatically. (2) file: list the desired waypoint names within a simple .txt files, with one name per line and the number of waypoint names must equal the number of waypoints in the .kml; the function will prompt to select the file. An example can be found in ‘agate/example_workflows/waypointNames.txt’ (3) manual: waypoint names are manually entered in the command window within the function call

% specify file name to .kml path
kmlFile = fullfile(CONFIG.path.mission, 'exampleTrack.kml');
% OR
% leave empty and will prompt to select .kml path
kmlFile = []; 

% specify radius
radius = 2000;

% create targets file, 3 options to name waypoints
% (1) prefix-based automated naming
prefix = 'WP'; % Any two letters make easy to reference and read options
targetsOut = makeTargetsFile(CONFIG, kmlFile, prefix, radius);
% OR
% (2) use a text file with list of waypoint names; will prompt to select .txt
targetsOut = makeTargetsFile(CONFIG, kmlFile, 'file', radius);
% OR
% (3) manually enter in command window when prompted
targetsOut = makeTargetsFile(CONFIG, kmlFile, 'manual', radius);

_{Back to top}

Plot planned track

The mapPlannedTrack function will create a simple map of the planned track with labeled waypoints. This function requires map extent to be defined in the configuration file. Bathymetry is optional and is toggled on or off with the bathyOn argument.

% set up map configuration
bathyOn = 1;
figNum = 26;

% use targetsOut file from above as input targets file
targetsFile = targetsOut;

% create plot
mapPlannedTrack(CONFIG, targetsFile, CONFIG.glider, bathyOn, figNum)


% get file name only for plot saving
[~, targetsName, ~] = fileparts(targetsFile);

% save as .png
exportgraphics(gcf, fullfile(CONFIG.path.mission, [CONFIG.glider '_' ...
    CONFIG.mission, '_plannedTrack_' targetsName, '.png']), ...
    'Resolution', 300)
% as .fig
savefig(fullfile(CONFIG.path.mission, [CONFIG.glider '_' CONFIG.mission, ...
    '_plannedTrack_' targetsName, '.fig']))

% save as .pdf or .eps - requires the export_fig toolbox available at
%  https://github.com/altmany/export_fig
export_fig(fullfile(CONFIG.path.mission, [CONFIG.glider '_' CONFIG.mission, ...
    '_plannedTrack_' targetsName, '.eps']), '-eps', '-painters');
export_fig(fullfile(CONFIG.path.mission, [CONFIG.glider '_' CONFIG.mission, ...
    '_plannedTrack_' targetsName, '.pdf']), '-pdf', '-painters');

_{Back to top}

Plot bathymetry profile

It can be useful to have a profile of the bathymetry the planned track will traverse, to highlight periods where the glider’s target dive depth may need to be adjusted more shallow, or can be extended deeper.

An indicator line (dashed red line) will be plotted at 990 m as the default (max $D_TGT for Seagliders) but can be specified to a different value with the yLine argument.

% can specify bathymetry file
bathyFile = 'C:\GIS\etopo\ETOPO2022_bedrock_30arcsec_MHI.tiff';
plotTrackBathyProfile(CONFIG, targetsFile, bathyFile)
% OR 
% leave empty to prompt to select file
plotTrackBathyProfile(CONFIG, targetsFile)

% save as .png
exportgraphics(gcf, fullfile(CONFIG.path.mission, [CONFIG.glider '_' ...
    CONFIG.mission, '_targetsBathymetryProfile_' targetsName, '.png']), ...
    'Resolution', 300)

Summarize planned track

The below code reads in an existing (or newly created!) targets file and will loop through to calculate the distance between each waypoint and then print out the total planned track distance. If an estimate of glider speed (in km/day) is available, that can be used to estimate mission duration.

% if no targetsFile specified, will prompt to select
[targets, targetsFile] = readTargetsFile(CONFIG);
% OR specify targetsFile variable from above
[targets, targetsFile] = readTargetsFile(CONFIG, targetsFile);

% loop through all targets (expect RECV), calc distance between waypoints
for f = 1:height(targets) - 1
    [targets.distToNext_km(f), ~] = lldistkm([targets.lat(f+1) targets.lon(f+1)], ...
        [targets.lat(f) targets.lon(f)]);
end

% specify expected avg glider speed in km/day
avgSpd = 15; % km/day

% print out summary
[targetsPath, targetsName, ~] = fileparts(targetsFile);
fprintf(1, 'Total tracklength for %s: %.0f km\n', targetsName, ...
    sum(targets.distToNext_km));
fprintf(1, 'Estimated mission duration, at %i km/day: %.1f days\n', avgSpd, ...
    sum(targets.distToNext_km)/avgSpd);

The output will look something like this:

>>
Total tracklength for targets_exampleTrack: 54 km
Estimated mission duration, at 15 km/day: 3.6 days
>>

_{Back to top}